Collection of Tools & Utilities/Collection of Tools and Utilities.iso/memory/emsaw41s.zip/MAN40.ASC

Text File | 1994-06-26 | 31KB | 814 lines

                          "Don't make things complex, make them useful."
                           Andrew Wolfenburg, 1993

                 Huge Arrays in Expanded Memory
          Accessible from Several Computer Languages
                         ver. 4.1, 4.1S

             (c) Copyright A. W. Wolfenburg, 1994


1. Instead of Introduction
---------------------------
   If you are a DOS programmer in C, Pascal, Fortran, Cobol, Clipper,
or some similar language on the IBM PC compatible and you want to use
huge arrays (up to 82 MB in total) in your programs and you have
a beloved compiler that you cannot abandon, my package is for you.

   Additionally, if you want to directly address fields with
lengths (1 to 32 bits) defined by you, and positions of these fields
are unrestricted in the scope of the arrays (fields may overlap word
boundaries), you will be able to do it with great ease.

   You need in your 286 or higher, an extended memory with
suitable size (1, 2, 4, 8 MB or more). A memory manager (e.g. EMM386.EXE
from DOS 5.0) will use this memory as expanded memory according
to LIM EMS (Expanded Memory Specification) 3.2 or 4.0. If you have a 286
you should use a different memory manager, e.g. shareware EMS40.SYS.
   A 486 50MHz IBM compatible with 64 MB RAM has been successfully
tested for the access to near 64 MB of EMS memory with the Quarterdeck
Memory Manager QEMM386.SYS.

   Now, you can forget about such terms as "mapping", "handle",
"frame", "caching", "aliasing", "segment", "offset", "physical
page", "logical page" and so on. In this case there exist only
arrays with a defined number of elements in which defined fields
can be located.

   Let others waste their time reading long and boring descriptions
of extended and expanded memory specifications, you can take advantage
of time saved for solving problems. You can locate up to 32,678-byte
long variables, records, coded characters and bit combinations in the
1-D, or any-D (up to 32,768-D) array elements and on the defined fields
of a 1-D array, and get back exactly what was put in. You can use up to
254 arrays according to LIM EMS 4.0 specification.
   For example this package will enable you to store variants of chess
moves for computer championship matches.

  The EM (expanded memory) can be allocated dynamically to particular
arrays and can be freed by calling suitable subroutines belonging to the
package. Before program termination the memory allocated to the arrays
should be freed, otherwise there may not be enough EMS or XMS memory
during execution of a later program.

  The size of the defined array is constant until the moment of
releasing the memory allocated to this array. Of course, after
memory has been released, program has been terminated or power shut
down, the content of the memory is lost.

  The software package has been written in pure assembly code, does not
need to use any libraries, and is very fast.

 2. To be specific:
--------------------

   Whatever programming languages you use, you deal with
subroutines. Those which return a value are called functions
in some languages. Subroutines compiled outside the main
program are called external subroutines. Several external
subroutines contained in one file and compiled together constitute
a module. The module can have the shape of an object file
(extension .obj).
   The subroutines of this package are contained in object files.
Basically there are two sets of these subroutines: with the C
calling convention (they are in the file emsw40c.obj) and with the
Pascal calling convention (they are in emsw40p.obj). The third file
segcl.obj contains subroutines which can be used together with
emsw40c.obj in Clipper programs which use Extended System. The Pascal
(Turbo Pascal) calling convention is also used in Fortran and Cobol
on the PC and can be used in these languages.
   All the parameters (arguments) of the package subroutines are
addresses (pointers) of the type segment:offset and point on two
words in the calling subroutine (except some calls in Clipper
- see the Clipper program example). This method of parameter
transferring is called "by reference or by pointer".

  To run any program with the package subroutines you should have
a Memory Manager installed. For example, if you use DOS 5.0 or
higher you might have in config.sys file the two lines:

device=himem.sys
device=emm386.exe <amount_of_mem_in_kilobytes_you_will_use> ram

or for 286s:
device=ems40.sys <amount_of_mem_in_kilobytes_you_will_use>

 The subroutines in the package are:
(= means function)

EMINIT() - initiates access to expanded memory and should be called
once, as the first, among the rest of the subroutines.

SIZEAR(t, f) - gives total t and current available f number of
array elements (4 byte integers) to allocate.

NEWAR(A, w) - allocates w 4 byte integer elements for an
array whose description is stored in A, a 2 bytes long system
variable associated with this array (so, we can call this array A).
You must not change the value of this variable.

SETINT(A, w, v) - sets value of the element w of array A to v (A
is 2 bytes long, w and v are 4 byte integers). Elements of arrays
are counted from 1.

=GETINT(A, w) - gets value of the element w of the array A and
returns this value to calling program (unit). GETINT must be 4 byte
integer.

GETINTCO(A, w, v) - gets value of the element w of the array A and
assigns this value to v, 4 byte integer variable. This procedure
can be called instead of GETINT in the languages without functions e.g.
COBOL.

SETF(A, w, b, l, v) - sets value of the field started in w element
of array A from the bit b with length l bits to the value of v.
Bits in all the elements of an array are counted from 0 to 31 from
left to right. If the value v is too big to fit in the defined field,
it is cut from the left side to the defined length l. The values of
adjoined fields will always stay unchanged in such a situation.

=GETF(A, w, b, l) -  gets value of the field started in w element
of array A from the bit b with length l bits and returns this value
to the calling program (unit) by assigning it to GETF. The type of
GETF can be 2 byte integer or 4 byte integer depending on the size
of the field.

GETFCO(A, w, b, l, v) - gets value of the field started in w element
of array A from the bit b with length l and assigns this value to
the v variable. This procedure can be called instead of GETF in the
languages without functions eg. COBOL.

FREEAR(A) - releases the expanded memory allocated for array A.

   Additionally for the version 4.0+ some new subroutines were
introduced.
   They enable usage of 1-D, 2-D and 3-D and any D arrays up to 32768-D.
Each element of these arrays can have length 1 to 32768 bytes. The
subroutines are contained in emsw40p.obj file for the Pascal calling
convention, and in emsw40c.obj for C calling convention.

These new subroutines are:

SIZA (t, f, i) - gives total t and available f amount of elements for
a new array having elements of the length of i bytes.

NEWA (A, i, l) - allocates i elements of the length l bytes (up to
32678) for an 1-D array whose description is stored in a 2 bytes long
system variable A is associated with this array (so, we can call this
array A). You must not change the value of this variable. The variable
i should be at least a 4 byte integer, and variable l should be at least
a 2 byte integer.

NEWA2 (A, i, j, l) - allocates i*j  elements of the length l (1 to
32678) bytes each, for an 2-D array whose description is stored in
a 2 byte long, system variable A, which is associated with this array
(so, we can call this array A). You must not change the value of this
variable. The variables i, j should be at least 4 byte integers and
variable l should be at least a 2 byte integer.

NEWA3 (A, i, j, k, l) - allocates i*j*k  elements of the length l
(1 to 32678) bytes each, for a 3-D array whose description is stored
in a 2 byte long, system variab